home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Performance Co-Pilot 1.3
/
SGI Performance Co-Pilot 1.3.iso
/
dist
/
pcp.idb
/
usr
/
share
/
catman
/
u_man
/
cat3
/
PMAPI
/
pmfetch.z
/
pmfetch
Wrap
Text File
|
1997-04-03
|
12KB
|
199 lines
PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333)))) PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
NNNNAAAAMMMMEEEE
ppppmmmmFFFFeeeettttcccchhhh - get performance metric values
CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>>
iiiinnnntttt ppppmmmmFFFFeeeettttcccchhhh((((iiiinnnntttt nnnnuuuummmmppppmmmmiiiidddd,,,, ppppmmmmIIIIDDDD ppppmmmmiiiiddddlllliiiisssstttt[[[[]]]],,,, ppppmmmmRRRReeeessssuuuulllltttt ********rrrreeeessssuuuulllltttt))))
cccccccc ............ ----llllppppccccpppp
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
Given a list of Performance Metric IDs (PMID)s, e.g. as constructed by
ppppmmmmLLLLooooooookkkkuuuuppppNNNNaaaammmmeeee(3), via _p_m_i_d_l_i_s_t and _n_u_m_p_m_i_d, fetch the values for these
performance metrics.
The call to ppppmmmmFFFFeeeettttcccchhhh is executed in the context of a source of metrics,
instance profile and collection time, previously established by calls to
the appropriate context and profile functions, namely some of
ppppmmmmNNNNeeeewwwwCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmDDDDuuuuppppCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmUUUUsssseeeeCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmAAAAddddddddPPPPrrrrooooffffiiiilllleeee(3),
ppppmmmmDDDDeeeellllPPPPrrrrooooffffiiiilllleeee(3) and ppppmmmmSSSSeeeettttMMMMooooddddeeee(3).
The principal result from ppppmmmmFFFFeeeettttcccchhhh is returned in the argument _r_e_s_u_l_t as a
tree, using the following component data structures;
typedef struct {
int len; /* length in bytes */
char vbuf[1]; /* one or more values */
} pmValueBlock;
typedef struct {
int inst; /* instance identifier */
union {
pmValueBlock *pval; /* pointer to value-block */
int lval; /* integer value insitu */
} value;
} pmValue;
typedef struct {
pmID pmid; /* metric identifier */
int numval; /* number of values or error code */
int valfmt; /* value style, insitu or ptr */
pmValue vlist[1]; /* set of instances/values */
} pmValueSet;
/* Result returned by pmFetch() */
typedef struct {
struct timeval timestamp; /* time stamped by collector */
int numpmid; /* number of PMIDs */
pmValueSet *vset[1]; /* set of value sets */
} pmResult;
PPPPaaaaggggeeee 1111
PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333)))) PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
To accommodate metrics with multiple value instances, the _n_u_m_v_a_l field
indicates how many values are returned for each requested PMID. The
field _v_a_l_f_m_t in the _p_m_V_a_l_u_e_S_e_t structure indicates if the values for this
metric are stored _i_n_s_i_t_u in the _l_v_a_l field, i.e. a 32-bit quantity
(either long, unsigned long or float, or if the values are held in
associated _p_m_V_a_l_u_e_B_l_o_c_k structures. The _p_m_V_a_l_u_e_B_l_o_c_k structure can
accommodate arbitrary sized binary data, and is suited for `string-
valued' metrics and metrics with aggregated or complex data types. It is
expected that the _i_n_s_i_t_u format will be the most common option.
If one value (i.e. associated with a particular instance) for a requested
metric is `unavailable' (at the requested time), then there is no
associated _p_m_V_a_l_u_e structure in the _r_e_s_u_l_t. If there are no available
values for a metric, then _n_u_m_v_a_l will be zero and the associated
_p_m_V_a_l_u_e[] instance will be empty (_v_a_l_f_m_t is undefined in these
circumstances, however _p_m_i_d will be correctly set to the PMID of the
metric with no values).
As an extension of this protocol, if the Performance Metrics Collection
System (PMCS) is able to provide a reason why no values are available for
a particular metric, this is encoded as a standard error code in the
corresponding _n_u_m_v_a_l. Since the error codes are all negative, values for
a requested metric are `unavailable' if _n_u_m_v_a_l is less than, or equal to,
zero. A performance metric's value may be `unavailable' for any of the
following reasons;
+ The metric is not supported in this version of the software for the
associated Performance Metric Domain
+ Collection is not currently activated in the software for the
associated Performance Metric Domain
+ The associated PMID is not known
+ The current system configuration does not include the associated
hardware component and/or the associated software module, e.g. a disk
is not installed, or off-line, or Oracle is not installed
+ The metric is one for which an instance profile is required, and none
was provided (there are a small number of metrics in this category,
typically ones with very large, and/or very dynamic instance domains,
and/or expensive metric instantiation methods).
In general, we may not be able to differentiate between the various
cases, and if differentiation is not possible, _n_u_m_v_a_l will simply be
zero.
The argument definition and the result specifications have been
constructed to ensure that for each PMID in the requested _p_m_i_d_l_i_s_t there
is exactly one _p_m_V_a_l_u_e_S_e_t in the _r_e_s_u_l_t, and further the PMIDs appear in
exactly the same sequence in both _p_m_i_d_l_i_s_t and _r_e_s_u_l_t. This makes the
number and order of entries in _r_e_s_u_l_t completely deterministic, and
PPPPaaaaggggeeee 2222
PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333)))) PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
greatly simplifies the application programming logic after the call to
ppppmmmmFFFFeeeettttcccchhhh.
The _r_e_s_u_l_t structure returned by ppppmmmmFFFFeeeettttcccchhhh is dynamically allocated using a
combination of mmmmaaaalllllllloooocccc(3C) calls and specialized allocation strategies,
and should be released when no longer required by calling ppppmmmmFFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(3)
- under no circumstances should ffffrrrreeeeeeee(3C) be called directly to release
this space.
As common error conditions are encoded in the _r_e_s_u_l_t data structure, we'd
expect only cataclysmic events to cause an error value to be returned.
One example would be if the metrics source context was a remote host, and
that host or the PMCS on that host became unreachable. Otherwise the
value returned by the ppppmmmmFFFFeeeettttcccchhhh function will be zero.
SSSSEEEEEEEE AAAALLLLSSSSOOOO
ppppmmmmAAAAddddddddPPPPrrrrooooffffiiiilllleeee(3), PPPPMMMMAAAAPPPPIIII(3), ppppmmmmDDDDeeeellllPPPPrrrrooooffffiiiilllleeee(3), ppppmmmmDDDDuuuuppppCCCCoooonnnntttteeeexxxxtttt(3),
ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee(3), ppppmmmmFFFFeeeettttcccchhhhAAAArrrrcccchhhhiiiivvvveeee(3), ppppmmmmFFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(3), ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3),
ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3), ppppmmmmLLLLooooooookkkkuuuuppppNNNNaaaammmmeeee(3), ppppmmmmNNNNeeeewwwwCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmSSSSeeeettttMMMMooooddddeeee(3),
ppppmmmmUUUUsssseeeeCCCCoooonnnntttteeeexxxxtttt(3) and ppppmmmmWWWWhhhhiiiicccchhhhCCCCoooonnnntttteeeexxxxtttt(3).
Note that ppppmmmmFFFFeeeettttcccchhhh is the most primitive method of fetching metric values
from the PMCS. More user friendly interfaces to the PMCS are available
or currently under development - these higher level fetch methods
insulate the user from the intricacies of context creation, setting up
instance profiles, _p_m_R_e_s_u_l_t traversal, and splitting fetches into batches
to minimize PDU traffic or according to other optimization criteria.
DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
As mentioned above, ppppmmmmFFFFeeeettttcccchhhh returns error codes _i_n_s_i_t_u in the argument
_r_e_s_u_l_t. If no result is returned, e.g. due to IPC failure using the
current PMAPI context, or end of file on an archive log, then ppppmmmmFFFFeeeettttcccchhhh
will return a negative error code which may be examined using
ppppmmmmEEEErrrrrrrrSSSSttttrrrr(3).
PPPPMMMM____EEEERRRRRRRR____EEEEOOOOLLLL
When fetching records from an archive log, ppppmmmmFFFFeeeettttcccchhhh returns this
error code to indicate the end of the log has been passed (or the
start of the log has been passed, if the direction of traversal is
backwards in time). If the ``mode'' for the current PMAPI context
(see ppppmmmmSSSSeeeettttMMMMooooddddeeee(3)) is PPPPMMMM____MMMMOOOODDDDEEEE____IIIINNNNTTTTEEEERRRRPPPP then the time origin is
advanced, even when this error code is returned. In this way
applications that position the time outside the range defined by the
records in the archive, and then commence to ppppmmmmFFFFeeeettttcccchhhh will eventually
see valid results once the time origin moves inside the temporal
span of the archive.
PPPPaaaaggggeeee 3333